home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audiofile / AFreadframes.z / AFreadframes
Encoding:
Text File  |  2002-10-03  |  9.0 KB  |  133 lines
  1.  
  2.  
  3.  
  4. aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))                                            aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afReadFrames - read sample frames from a specified audio track in an
  10.      audio file
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((ccccoooonnnnsssstttt AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt ttttrrrraaaacccckkkk,,,,
  16.                       vvvvooooiiiidddd ****ssssaaaammmmpppplllleeeessss,,,, ccccoooonnnnsssstttt iiiinnnntttt ccccoooouuuunnnntttt))))
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  19.      _f_i_l_e      is the AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure for the audio file from which
  20.                audio sample data will be read.  This structure is usually the
  21.                returned value of a call to aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm).
  22.  
  23.      _t_r_a_c_k     is an integer which identifies an audio track in a file.
  24.  
  25.                Since all currently supported file formats allow at most one
  26.                audio track per file, the value AAAAFFFF____DDDDEEEEFFFFAAAAUUUULLLLTTTT____TTTTRRRRAAAACCCCKKKK should always
  27.                be used for this argument for now.
  28.  
  29.      _s_a_m_p_l_e_s   is a pointer to a buffer into which you want to transfer the
  30.                samples read from the audio file.  Note that the data type of
  31.                the samples in this buffer can vary depending on the sample
  32.                format and sample width of the file.
  33.  
  34.      _c_o_u_n_t     is the number of sample _f_r_a_m_e_s to be read from the audio track.
  35.  
  36.                For monaural data a sample frame is a single sample; for stereo
  37.                data a sample frame is a pair of samples, etc.
  38.  
  39. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  40.      aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) returns the number of sample frames actually read from the
  41.      file. In the event of error, -1 is returned and oooosssseeeerrrrrrrroooorrrr(3C) will be set
  42.      to the appropriate error code.
  43.  
  44. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  45.      aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) transfers data from the specified track of an audio file
  46.      to the _s_a_m_p_l_e_s buffer.  _s_a_m_p_l_e_s should be of type cccchhhhaaaarrrr****, sssshhhhoooorrrrtttt****, iiiinnnntttt****,
  47.      uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt****, ffffllllooooaaaatttt****, or ddddoooouuuubbbblllleeee**** depending on the width and format of
  48.      the samples in the audio track as retrieved using aaaaffffGGGGeeeettttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm),
  49.      or the virtual format specified by aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm).
  50.      aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) attempts to read _c_o_u_n_t sample frames from the file,
  51.      starting at the current location of the file read pointer.
  52.  
  53.      When a file is opened with read access by aaaaffffOOOOppppeeeennnnFFFFDDDD(3dm),
  54.      aaaaffffOOOOppppeeeennnnNNNNaaaammmmeeeeddddFFFFDDDD(3dm), or aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm), the file pointer for each audio
  55.      track is initialized to point to the first sample frame in the audio
  56.      track. The pointer may be moved to any sample frame location within a
  57.      specified track by a call to aaaaffffSSSSeeeeeeeekkkkFFFFrrrraaaammmmeeee(3dm).
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))                                            aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      Before returning, aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) automatically updates the read pointer
  75.      for _t_r_a_c_k  so that it points to the sample frame following the last one
  76.      copied into _s_a_m_p_l_e_s.
  77.  
  78.      Note that the data type of the samples in this buffer can vary depending
  79.      on the sample format and sample width of the samples in the _t_r_a_c_k.  The
  80.      _s_a_m_p_l_e_s buffer is interpreted differently depending on the current
  81.      configuration of the audio track.  The _s_a_m_p_w_i_d_t_h parameter returned by
  82.      aaaaffffGGGGeeeettttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) may or may not be meaningful, depending on the
  83.      value of _s_a_m_p_f_m_t.  See aaaaffffGGGGeeeettttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) for a full explanation of
  84.      sample representations.
  85.  
  86.      aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) automatically decompresses data which was encoded with the
  87.      CCITT G.722, CCITT G.711, MPEG, and Aware compression.  By default, the
  88.      data for all currently supported compression formats is presented to
  89.      application programs in the standard two's complement linear PCM format,
  90.      but this is by no means guaranteed for future compression types.  See
  91.      aaaaffffGGGGeeeettttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(3dm) and aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt for further
  92.      information.  To achieve real-time G.722 compression, the application
  93.      process may require non-degrading scheduling priority (see sssscccchhhheeeeddddccccttttllll(2) or
  94.      nnnnpppprrrriiii(1))
  95.  
  96.      If an audio track contains data for more than a single audio channel, the
  97.      data returned in the _s_a_m_p_l_e_s buffer will be interleaved.  For stereo
  98.      data, the samples are always grouped in left/right pairs (sample frames).
  99.      For reference, interleave conventions for files containing multichannel
  100.      data are stated in the AIFF-C spec.
  101.  
  102. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  103.      To read 10000 stereo sample frames (i.e., 20000 individual audio samples)
  104.      from a stereo AIFF-C file which contains G.722-encoded data, declare
  105.      _s_a_m_p_l_e_s to be a sssshhhhoooorrrrtttt[[[[]]]] buffer (since G.722 encodes 16-bit data) with at
  106.      least 20000 locations, and call aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(((()))) with _c_o_u_n_t set to 10000.
  107.  
  108. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  109.      This routine will not function correctly if the user changes the file
  110.      position on the file descriptor for the AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee being manipulated.
  111.      See aaaaffffSSSSaaaavvvveeeeFFFFiiiilllleeeePPPPoooossssiiiittttiiiioooonnnn(3dm) and the section _C_A_V_E_A_T_S _F_O_R _U_S_I_N_G _T_H_E
  112.      _H_A_N_D_L_E'_S _F_I_L_E _D_E_S_C_R_I_P_T_O_R in aaaaffffIIIInnnnttttrrrroooo(3dm) for some important information
  113.      about how to deal with this situation.
  114.  
  115. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  116.      afOpenFile(3dm), afSeekFrame(3dm), afGetSampleFormat(3dm),
  117.      afWriteFrames(3dm), afGetCompression(3dm), afSetVirtualSampleFormat(3dm),
  118.      afGetVirtualSampleFormat(3dm)
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.